home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 5 / MacMania 5.toast / / Tools&Utilities / BibTeX ƒ / BibTeX.ReadMe < prev    next >
Text File  |  1996-11-19  |  17KB  |  366 lines
  1. # ###################################################################
  2. # 
  3. #  FILE: "BibTeX.ReadMe"
  4. #                                    created: 4/2/96 {6:50:21 pm} 
  5. #                                last update: 19/11/96 {2:23:43 pm} 
  6. #  Author: Vince Darley
  7. #  E-mail: <mailto:vince@das.harvard.edu>
  8. #    mail: Division of Applied Sciences, Harvard University
  9. #          Oxford Street, Cambridge MA 02138, USA
  10. #     www: <http://www.fas.harvard.edu/~darley/>
  11. #  
  12. #  Mac port copyright (C) 1996 Vince Darley.
  13. #
  14. #  Freely distributable, please report bugs (and fixes) to
  15. #  the author.
  16. #
  17. # ###################################################################
  18.  
  19. This is BibTeX (fat)
  20. ====================
  21.  
  22. Contents:
  23.  
  24.     (i)     Description of BibTeX's function and purpose.
  25.     (ii)     Feature list for this version of BibTeX for MacOS.
  26.     (iii)     Using BibTeX with the editor 'Alpha'
  27.     (iv)      Technical details, compilation, to-do's,...
  28.     (v)        Version history.
  29.  
  30. BibTeX is the bibliography handling tool related to the TeX/LaTeX 
  31. typesetting system (available on almost all conceivable OS platforms).  
  32. When a document is typeset with LaTeX, an auxiliary file (with extension 
  33. '.aux') is generated.  This auxiliary file contains, amongst other things, 
  34. a list of references (to books, articles, research reports, web-url's,...)  
  35. cited in the original document.  BibTeX takes this list, together with the 
  36. name of a style file (extension '.bst') and a list of bibliography 
  37. databases (extension '.bib') which are also given in the auxiliary file, 
  38. and produces a wonderfully formatted list of references which the LaTeX 
  39. system subsequently (and automatically) appends to your typeset document.
  40.  
  41. Hence BibTeX is really not at all useful without TeX/LaTeX (there are 
  42. several freeware/shareware/commercial versions for the MacOS: OzTeX, 
  43. CMacTeX, DirecTeX Pro, Textures).  In fact this port of BibTeX is now 
  44. distributed with OzTeX 2.0 or newer (although the actual version shipping 
  45. with OzTeX can lag behind the latest by a release or two).  It is useful 
  46. to have a good text editor which knows about the particular format of LaTeX 
  47. documents: on the Mac, the editor Alpha is indispensible in this regard, 
  48. both for editing and for its apple-event communication with the various 
  49. parts of a LaTeX system.
  50.  
  51. For those who think this sounds a bit too complicated, the benefits in 
  52. terms of quality of output (both textual and mathematical) and automatic 
  53. generation of all manner of numbering schemes (figures, equations, 
  54. sections), and document parts (table of contents, index, bibliography), 
  55. together with cross-platform availability, mean that many people consider 
  56. it the _best_ current system for producing quality documents.
  57.  
  58. Here are some links for further information:
  59.  
  60. •    Mathematical relevance: <http://e-math.ams.org/>
  61. •    General TeX documentation: <http://www.cl.cam.ac.uk/TeXdoc/TeXdocs.html>
  62. •    Archive of LaTeX documenation: <http://www.loria.fr/tex/english/index.html>
  63. •    More LaTeX links: <http://molscat.giss.nasa.gov/LaTeX/externals.html>
  64. •    The editor 'Alpha': <http://www.cs.umd.edu/~keleher/alpha.html>
  65. •    Various TeX-related links: <http://www.bluesky.com/TeXlinks>
  66. •    CMacTeX: <http://www.math.tamu.edu/~tkiffe/cmactex.html>
  67. •    OzTeX: <http://www.kagi.com/authors/akt/oztex.html>
  68. •    Textures: <http://www.bluesky.com/>
  69. •    Archive of all TeX related material: <http://jasper.ora.com/ctan.html>
  70.  
  71. Many thanks to Alun Carr, Andy Amann, Richard Chang, Jacques Distler, and 
  72. others for helping to track down the bugs my port of BibTeX has had, and 
  73. for suggestions on how to improve it.
  74.  
  75. ========================================================================
  76.  
  77. BibTeX version 1.1.4
  78.  
  79. It has no known bugs, however, use at your own risk; there is no 
  80. warranty....  
  81.  
  82. Feature list: 
  83.  
  84. •    Basic features
  85.    -  Processes .aux files
  86.    -  Examine new or old log files and cmd-click to jump to errors, 
  87.       warnings, etc. in your editor.
  88.    -  Very fast (now more than 10 times faster!).
  89.    -  Friendly to other applications (actually calls WaitNextEvent);
  90.    -  Fat binary; runs on PPC or 68k machines;
  91.    -  Copes with both Unix and Mac standard eol characters.
  92.    -  Internet Config aware
  93.  
  94. •    TeX details:
  95.    -  Switchable between 'big' and 'small' modes.  The 'big' mode increases
  96.       the size of biobiography resources such as the number of strings allowed.
  97.       This should let you use 'Camel' the up-and-coming bibliography stuff for
  98.       LaTeX2e;
  99.    -  Search path (for .bib, .bst files) is as follows: (1) The two paths 
  100.       you set in the options dialog (2) the "BibTeX inputs" folder, 
  101.       (3) the location of the '.aux' file being processed.  This search 
  102.       path is used for both .bst and .bib files, although you can of course 
  103.       keep them in separate directories if you like;
  104.    -  Source code available;
  105.  
  106. •   Interface details:
  107.    -  Supports high-level apple events etc. so you can drag a '.aux' file (or 
  108.       several) onto it for processing, or send it an odoc event from Alpha...
  109.    -  You can command-click on warnings, errors and filenames in
  110.       the log window to leap to the correct file, line, error position
  111.       etc. in your favorite editor.  Read the section 'Apple-events and
  112.       BibTeX' for more details.  To use this feature with the editor
  113.       'Alpha', copy the contents of the file 'AlphaBibScripts.tcl' to 
  114.       your 'prefs.tcl' in Alpha.
  115.    -  Links from the about box to the BibTeX web page, so you can check
  116.       for upgrades.
  117.    -  If available, it uses Internet Config for file types of the .blg, .bbl 
  118.       files it creates.  If you make BibTeX ('Vbib') the creator of
  119.       .blg files, you can double click them to open them in the log window.
  120.    -  Balloon help is available for all dialog box items.
  121.    
  122.    
  123. This version of BibTeX is totally free.  If you like it, feel free to
  124. send email, postcards, cash, registrations to shareware you've written,...
  125. but there is no obligation.
  126.  
  127. Note that the application's partition is generous at 400k by default.  I 
  128. think it should work with 375k on 680x0 machines, and 300k on PPC machines, 
  129. so you could lower the application's partition size.
  130.  
  131. ========================================================================
  132.  
  133. Apple-Events and BibTeX
  134.  
  135. BibTeX can be triggered to process '.aux' files by being sent a standard 
  136. 'odoc' event.  Versions of Alpha newer than 6.2 will do this without any 
  137. configuration on your part.  If you're using an old version of Alpha (pre 
  138. 6.2), download a new version (see the hyperlinks above); (Also have a look 
  139. at my package "Vince's Additions" which contains some useful bibliography 
  140. conversion tools).  If you don't have Alpha, download it immediately; it's
  141. easily the best editor for TeX, LaTeX, C, C++ etc. (IMHO).
  142.  
  143. As of version 1.1.4, command-clicking in the log window will now send GURL 
  144. 'bibresult' events.  To make use of these, open Internet Config, select 
  145. 'helpers' and 'add' a helper for 'bibresult', and select as helper your 
  146. editor.  Of course your editor needs to be able to receive and interpret 
  147. GURL bibresults.  I've enclosed some procedures for Alpha which do this, 
  148. but if you use BBEdit/TeXtures or something else, you're currently on your 
  149. own.
  150.  
  151. The format of the 'bibresult' GURL event is as follows:
  152.  
  153.     bibresult:FULLFILENAME:MESSAGE
  154.  
  155. where FULLFILENAME is a full path description to the base '.aux' file or
  156. 'Unknown', and MESSAGE is any of the following:
  157.  
  158.     The top-level auxiliary file: FILENAME.aux
  159.     A level-X auxiliary file: FILENAME.aux
  160.     Warning--I didn't find a database entry for "ENTRY"
  161.     Database file #X: FILENAME.bib
  162.     Warning--WARNING ENTRY
  163.     The style file: FILENAME.bst
  164.     ERROR---line LINENUM of file FILENAME a 'UP-TO-ERROR' at POSITION
  165.  
  166. where X is an integer; FILENAME is a just the name, with no path given;
  167. ENTRY is a citation key such as 'Darley1996'; WARNING is a standard
  168. BibTeX warning (such as 'empty title in'); ERROR is a standard BibTeX
  169. error (such as 'Repeated entry'); LINENUM is the line number of an
  170. error; POSITION is the character position in that line at which the
  171. error was detected; UP-TO-ERROR is the string of characters from the 
  172. beginning of the line to the start of the error, with braces {} replaced 
  173. by ‘’ because of some IC/AE problem.
  174.  
  175. The Tcl procedures I've written for Alpha interpret these messages and take 
  176. the appropriate action: opening a file; finding and highlighting an error; 
  177. adding a '.bib' file to the \bibliography environment; making a new entry 
  178. in an existing '.bib' file,… To use these scripts, copy the contents of the 
  179. file 'BibTeXAlphaScripts.tcl' to your 'prefs.tcl' in Alpha (or read the 
  180. file for other installation options).
  181.  
  182. Problems/Bugs:
  183.  
  184. Since BibTeX sends actual line numbers and positions, if you're correcting 
  185. a lot of errors/warnings, those line number can become out of date.  The 
  186. receiving scripts are designed to alleviate this problem (they search 
  187. locally for something matching the error), but with heavy editing, these 
  188. problems are not completely avoidable.
  189.  
  190. ========================================================================
  191.  
  192. Technical Stuff:
  193.  
  194. To Do:
  195.  
  196. •    Write to .blg and .bbl files asynchronously.
  197. •    Some minor code tidying.
  198. •    Incorporate updated powerplant classes when available.
  199. •    A few _minor_ speed improvements are still possible.
  200. •    Perhaps switch to using WASTE, instead of TextEdit.
  201.  
  202. Any offers for help or suggestions for improvements much appreciated --- in 
  203. particular if someone wants to get to work on the to-do's, that'd be great.
  204. If you have example code which does something similar to any of the to-do's
  205. (e.g. asynchronous file i/o), and you're happy to let me use it as a 
  206. template, then please send me it!
  207.  
  208. ------
  209.  
  210. Sources:
  211.  
  212. I'm no longer distributing the sources, since it seems a bit needless, but
  213. if you actually want them, just ask.  
  214.  
  215. Based on the C code of the original MacBibTeX (0.99c) which I grabbed from 
  216. CTAN, and code generously donated by Rick Zaccone from his 'Makeindex'.  
  217. Icon adapted from one I grabbed off a folder from some collection on the 
  218. net.  'IC++' written by Dan Crevier is used for the about box links.  I 
  219. also use LBalloonTracker by Paul Lalonde which is © 1996 Corporate Software 
  220. & Technologies Int.  Inc.  (CS&T), and very convenient.  Many thanks!
  221.  
  222. ------
  223.  
  224. Compilation (with CodeWarrior 10):
  225.  
  226. Obtain the library 'MoreFiles' (preferably version 1.4.3 or newer), which
  227. should be available from the info-mac archives.
  228.  
  229. •    Open the source code folder
  230. •    Compile BibTeX68k.µ
  231. •    Compile BibTeXPPC.µ
  232.  
  233. Move the resulting application "BibTeX" up one level so it can find 'BibTeX 
  234. inputs'.  You may need to adjust the memory allocation (with Get Info), but 
  235. beyond that you're set.
  236.  
  237. -----
  238.  
  239. Personalisation:
  240.  
  241. You can now set BibTeX search paths using the options dialog, but if for 
  242. some peculiar reason you want to set more than two different paths, in 
  243. addition to the defaults, then you can do so using ResEdit:
  244.  
  245. You can edit a string resource with ResEdit to specify your own search 
  246. path.  To do this open the app with ResEdit and look at the STR# resource 
  247. called "Path".  You can add entries which look like this:
  248. '2:Hard Disk:My Search Path:'; the '2' signifies to BibTeX that this is
  249. a complete path specification.  If you prefer, '0:' indicates 
  250. a path relative to the .aux file, and '1:' relative to the BibTeX 
  251. application.
  252.  
  253. ------
  254.  
  255. Version History:
  256.  
  257. 1.1.4    Fixed crashing bug when cmd-clicking at the end of the log window.
  258.         Fixed a couple small GUI buglets.  Added processing time message
  259.         to end of log window.  Command clicking in opened .blg files sends
  260.         correct file information now.  Minor changes to about box, and to
  261.         Tcl scripts for Alpha communication.
  262.  
  263.         Fixed so prefs file has an icon; startup will be slow the first
  264.         time, because BibTeX will have to rewrite your preferences.  
  265.         Added an icon resource for TEXT files which can be used for .blg 
  266.         log files.  Set this up in Internet Config, and you can double 
  267.         click .blg files to launch.  Now you can look at old .blg files and 
  268.         decide if you wish to regenerate them (cmd-G = Go will reprocess 
  269.         the corresponding .aux file), or cmd-click to edit problems using 
  270.         your editor.  Fixed quite old (I think) bug in which you could have 
  271.         two log windows after hitting 'Cancel' in the options dialog.
  272.         Feature change: BibTeX now rejects any text file that's not '.aux' 
  273.         or '.blg'; before it would be passed to the core code and of course
  274.         cause errors.  Added more Balloon help.  Feature change: type/creator
  275.         of .blg and .bbl files created are taken from Internet Config if 
  276.         possible, if not then from the .aux file as before.
  277.  
  278.         Copes with filenames containing spaces.  Remember if you use
  279.         spaces, your files will not work on other platforms.  Fixed a 
  280.         minor buffer-overflow problem in which not all warnings would
  281.         be given in the log window.  Added command-clicking features
  282.         to the log window (very useful and cool new feature!).  Fixed
  283.         one source of preferences problems (startup with no preferences
  284.         file, quit and restart => default preferences are garbage).
  285.         
  286. 1.1.3    Really fixed end-of-file problem.  Other minor changes.
  287.  
  288. 1.1.2   Fixed setting end-of-files correctly.  I somehow reintroduced this
  289.         bug when I rewrote all the file i/o stuff.  Balloon help in dialogs.
  290.         
  291. 1.1.1    Added options 'Stay open on warning', 'Stay open on error' which
  292.         counter-act the 'Quit when finished' option, and leave BibTeX
  293.         open if anything went wrong.
  294.         Fixed the 'text-jumping' visual bug in the log window (thanks
  295.         to a helpful soul on comp.sys.mac.programmer.codewarrior).
  296.         Updated to MoreFiles 1.4.3.
  297.         Preferences file now has its version number updated if necessary
  298.         when you start BibTeX, and I always create a preferences file now,
  299.         and any old preferences are updated with any new options.
  300.         This fixes an old 'bug' in which BibTeX would take a long time
  301.         starting up, because it's looking for a preferences file, or
  302.         trying to read information from it which doesn't exist.
  303.         Fixed a subtle 68k only bug which has been around for a long time,
  304.         but only now reared its head --- caused horrible crashes on 68k
  305.         machines, somewhat randomly since useful memory was being 
  306.         over-written.  However it's fixed now.
  307.         Fixed a small bug introduced in 1.10, which would show up only
  308.         after multiple runs, especially after a fatal error, and could 
  309.         result in a crash.
  310.         Added message to the log window after a fatal error.
  311.         
  312. 1.1.0    Did some serious profiling and optimisation.  Opening files is
  313.         really rather slow on MacOS, probably due to the emulated nature
  314.         of the file-system.
  315.         Now about 10+ times faster than 1.06.  Rough timing is as follows:
  316.         v1.06 75secs, v1.07 62secs, v1.10 7secs
  317.         (All using Speed Doubler on a 5300cs on a large BibTeX run) 
  318.         Huge rewrite of all the IO code: uses PowerPlant buffered IO classes,
  319.         which makes everything rather simpler, and on the whole a lot faster.
  320.         The code is much, much cleaner now, as I've cleared out a lot of the
  321.         old vestiges of MakeIndex and the ancient web2c source code has been
  322.         modernised.  Therefore the BibTeX <-> Interface links are simple now.
  323.         Added option to monopolise the CPU.
  324.         Significant interface improvements:
  325.         You can now set two folders to search in the options dialog box,
  326.         (but the old technique of using Resedit still works).  Note that
  327.         by default BibTeX now searches in:
  328.         • The same folder as the '.aux' file being processed.
  329.         • The folder 'BibTeX inputs' located wherever the BibTeX application
  330.         resides on your hard drive.
  331.         • Any folders you add manually using ResEdit (not normally necessary)
  332.         • The two folders you specify in your preferences.
  333.         Added links from the 'about box' to the BibTeX web-page, and to
  334.         mail me, etc.
  335.         Recompiled using Codewarrior 10
  336. 1.07    (Never released publicly)
  337.         Significant internal changes:
  338.         (i) Speed increases. 
  339.         (ii) Increased sizes of things for 'Big' mode.  This version of BibTeX
  340.         should support Camel (the up-and-coming LaTeX 2e bibliography system).
  341.         (iii) Added a couple of options which were requested: 
  342.         'beep when finished' and 'no log window'.
  343. 1.06    Now copes with extended character set 'üöé...'.  Not all TeX
  344.         implementations allow them, but if you pass one to BibTeX, it
  345.         will happily output it, assuming your version of TeX can cope.
  346.         Changed name of log window.
  347. 1.05    Recompiled with CW9, updated to take account of Powerplant
  348.         changes.  Cosmetic change when selecting 'go' to re-run
  349.         a file - the window is now cleared first.
  350. 1.04    Minor (non-fatal) bug fixes --- all files properly closed and 
  351.         flushed after a bibtex error, file eof's set correctly for .bbl 
  352.         and .blg files.
  353.         Thanks for the bug reports!
  354. 1.03    Minor changes --- it now gives a message 'BibTeX run complete.'
  355.         in the log window, rather than just finishing.  Documentation
  356.         update.  I've fixed the FREF/BNDL problems, so drag'n'drop
  357.         really should work now ;-)
  358. 1.02    Switchable between Big and Small.  Uses new memory allocation
  359.         scheme from Rick, so temporary memory is used rather than the
  360.         system heap.  This means the application's given partition can
  361.         be much smaller (300k works for me). Added fref 'TEXT' resource
  362.         which was missing previously (so drag and drop will work under
  363.         all circumstances now).
  364. 1.01    Copes with Unix as well as Mac EOL characters
  365. 1.0        Original; soon to be distributed with OzTeX 2.0
  366.